/** 
 * Copyright (C) 2012 Foxit Corporation.
 * All Rights Reserved.
 *
 * The following code is copyrighted and contains proprietary information and trade secrets of Foxit Corporation. 
 * You can only redistribute files listed below to customers of your application, under a written SDK license agreement with Foxit. 
 * You cannot distribute any part of the SDK to general public, even with a SDK license agreement. 
 * Without SDK license agreement, you cannot redistribute anything.
 *
 * @file	fpdfimage.h
 * @brief	Header file for the PDF Image module.
 * @details	The form field module offers methods which implement the following functions:
 *			1. Support to load the image file of multi-types, and convert it to PDF image pageobject.
 *			2. Support to import converted PDF image pageobject to PDF document or specific page.
 *			<br>
 * @note	If you want to purchase Foxit PDF SDK license and use ANY of the following functions, please
 *			request for enabling Edit module explicitly. 
 */

/** 
 * @addtogroup FGSPDFIMAGE PDF Image
 * @brief Methods in this module are included in fpdfimage.h
 */
 
/** @{*/
#ifndef __FGSIMAGE__
#define __FGSIMAGE__

#include "fpdfbase.h"

#ifdef __cplusplus
extern "C" {
#endif

 /**
 * @brief FGSPDF Image object.
 */
typedef const struct __FGSImage * FGSImageRef;

/**
 * @brief Load an image from file stream.
 *
 * @param[in] file			The path string of file.		
 *
 * @return	Reference to the image.
 */
FGSImageRef FGSImageLoadImage(CFStringRef file);
    
/**
 * @brief Get the image type.
 *
 * @param[in] image				Reference to the image.
 *
 * @return	The image type, see definitions <b>FGSPDFImageType</b>.
 */
FGSPDFImageType FGSImageGetImageType(FGSImageRef image);
    
/**
 * @brief Enable transparent image.
 *
 * @param[in] image				Reference to the image.
 * @param[in] bEnable			Whether enable or disable the transparent image.
 *
 * @return	::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSImageEnableImageTransparent(FGSImageRef image, Boolean bEnable);
    
/**
 * @brief Set the background color of the image.
 *
 * @param[in] image				Reference to the image.
 * @param[in] color				The background color.
 *
 * @return	::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSImageSetImageBGColor(FGSImageRef image, UInt32 color);

/**
 * @brief Set the opacity of the image.
 *
 * @param[in] image				Reference to the image.
 * @param[in] opacity			The opacity of the image.
 *
 * @return	::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSImageSetImageOpacity(FGSImageRef image, SInt32 opacity);
    
/**
 * @brief Get the count of frames.
 *
 * @param[in] image				Reference to the image.		
 *
 * @return	The count of the image frames.
 */
SInt32 FGSImageCountImageFrames(FGSImageRef image);
    
/**
 * @brief Load the specific image frame.
 *
 * @param[in] image				Reference to the image.
 * @param[in] frameIndex		
 *
 * @return	::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSImageLoadImageFrame(FGSImageRef image, SInt32 frameIndex);
    
/**
 * @brief Get the size of the image frame.
 *
 * @param[in] image				Reference to the image.
 * 
 * @return	The width of the frame.
 */
SInt32 FGSImageGetFrameWidth(FGSImageRef image);

/**
 * @brief Get the size of the image frame.
 *
 * @param[in] image				Reference to the image.					
 * 
 * @return	The height of the frame.
 */
SInt32 FGSImageGetFrameHeight(FGSImageRef image);
	
/**
 * @brief Get the CGImage of the image frame.
 *
 * @param[in] image				Reference to the image.
 * 
 * @return	The CGImage of the image frame.
 */
CGImageRef FGSImageCopyNativeImage(FGSImageRef image);
    
/**
 * @brief Free the image.
 *
 * @param[in] image				Reference to the image.
 * 
 * @return	::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSImageFreeImage(FGSImageRef image);
	
/**
 * @brief Create a image object from the image.
 *
 * @param[in] image				Reference to the image.
 * @param[in] doc				Reference to a PDF document.
 * @param[in] nFrame			The index of the frame.
 * 
 * @return	The generated image object.
 */
FGSPDFPageObjectRef FGSPDFCreatePdfImageObject(FGSImageRef image, FGSPDFDocumentRef doc, SInt32 nFrame);

/**
 * @brief Insert the image to the PDF Page.
 *
 * @param[in] image				Reference to the image.
 * @param[in] page				Reference to a PDF page.
 * @param[in] pos				The position of the page object which to insert after.
 * @param[in] frameIndex		The index of the frame.
 * @param[in] matrix			The matrix which the image transform with.
 * 
 * @return	The generated image object.
 */
FGSErrorRet FGSPDFInsertImageToPage(FGSImageRef image, FGSPDFPageRef page, FGSPDFPageObjectPosRef pos, SInt32 frameIndex, CGAffineTransform matrix, FGSPDFPageObjectRef* imageObj);

/**
 * @brief Insert the image to the PDF document.
 *
 * @param[in] image				Reference to the image.
 * @param[in] doc				Reference to a PDF document.
 * @param[in] iPageStart		The start index of the page which to insert the image.
 * @param[in] iFrameStart		The start index of the frame.
 * @param[in] iFrameCount		The total count of image frames to be inserted to the page. 
 * 
 * @return	::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFInsertImageToDocument(FGSImageRef hImage, FGSPDFDocumentRef doc, SInt32 iPageStart, SInt32 iFrameStart, SInt32 iFrameCount);

#ifdef __cplusplus
};
#endif

#endif // __FGSIMAGE__
/**@}*/

